home *** CD-ROM | disk | FTP | other *** search
/ The CICA Windows Explosion! / The CICA Windows Explosion! - Disc 2.iso / demo / wemdemo4.zip / INFO / ELISP.11 < prev    next >
Text File  |  1994-09-21  |  52KB  |  1,235 lines
  1. Info file elisp, produced by Makeinfo, -*- Text -*- from input file
  2. elisp.texi.
  3.  
  4.    This file documents GNU Emacs Lisp.
  5.  
  6.    This is edition 1.03 of the GNU Emacs Lisp Reference Manual,   for
  7. Emacs Version 18.
  8.  
  9.    Published by the Free Software Foundation, 675 Massachusetts
  10. Avenue,  Cambridge, MA 02139 USA
  11.  
  12.    Copyright (C) 1990 Free Software Foundation, Inc.
  13.  
  14.    Permission is granted to make and distribute verbatim copies of
  15. this manual provided the copyright notice and this permission notice
  16. are preserved on all copies.
  17.  
  18.    Permission is granted to copy and distribute modified versions of
  19. this manual under the conditions for verbatim copying, provided that
  20. the entire resulting derived work is distributed under the terms of a
  21. permission notice identical to this one.
  22.  
  23.    Permission is granted to copy and distribute translations of this
  24. manual into another language, under the above conditions for modified
  25. versions, except that this permission notice may be stated in a
  26. translation approved by the Foundation.
  27.  
  28.  
  29. 
  30. File: elisp,  Node: Using Interactive,  Next: Interactive Codes,  Prev: Defining Commands,  Up: Defining Commands
  31.  
  32. Using `interactive'
  33. -------------------
  34.  
  35.    This section describes how to write the `interactive' form that
  36. makes a Lisp function an interactively-callable command.
  37.  
  38.  * Special Form: interactive ARG-DESCRIPTOR
  39.      This special form declares that the function in which it appears
  40.      is a command, and that it may therefore be called interactively
  41.      (via `M-x' or by entering a key sequence bound to it).  The
  42.      argument ARG-DESCRIPTOR declares the way the arguments to the
  43.      command are to be computed when the command is called
  44.      interactively.
  45.  
  46.      A command may be called from Lisp programs like any other
  47.      function, but then the arguments are supplied by the caller and
  48.      ARG-DESCRIPTOR has no effect.
  49.  
  50.      The `interactive' form has its effect because the command loop
  51.      (actually, its subroutine `call-interactively') scans through
  52.      the function definition looking for it, before calling the
  53.      function.  Once the function is called, all its body forms
  54.      including the `interactive' form are executed, but at this time
  55.      `interactive' simply returns `nil' without even evaluating its
  56.      argument.
  57.  
  58.    There are three possibilities for the argument ARG-DESCRIPTOR:
  59.  
  60.    * It may be omitted or `nil'; then the command is called with no
  61.      arguments.  This leads quickly to an error if the command
  62.      requires one or more arguments.
  63.  
  64.    * It may be a Lisp expression that is not a string; then it should
  65.      be a form that is evaluated to get a list of arguments to pass
  66.      to the command.
  67.  
  68.    * It may be a string; then its contents should consist of a code
  69.      character followed by a prompt (if required for that code
  70.      character).  The prompt ends either with the end of the string
  71.      or with a newline.  Here is a simple example:
  72.  
  73.           (interactive "bFrobnicate buffer: ")
  74.  
  75.      The code letter `b' says to read the name of an existing buffer,
  76.      with completion.  The buffer name will be the sole argument
  77.      passed to the command.  The rest of the string is a prompt.
  78.  
  79.      If there is a newline character in the string, it terminates the
  80.      prompt.  If the string does not end there, then the rest of the
  81.      string should contain another code character and prompt,
  82.      specifying another argument.  Any number of arguments may be
  83.      specified in this way.
  84.  
  85.      If the first character in the string is `*', then an error is
  86.      signaled if the buffer is read-only.  Otherwise, the following
  87.      character is the first code character.
  88.  
  89.  
  90. 
  91. File: elisp,  Node: Interactive Codes,  Next: Interactive Examples,  Prev: Using Interactive,  Up: Defining Commands
  92.  
  93. Code Characters for `interactive'
  94. ---------------------------------
  95.  
  96.    The code character descriptions below contain a number of key
  97. words, defined here as follows:
  98.  
  99. Completion
  100.      Provide completion.  TAB, SPC, and RET perform name completion
  101.      because the argument is read using `completing-read' (*note
  102.      Completion::.).  `?' displays a list of possible completions.
  103.  
  104. Existing
  105.      Require the name of an existing object.  An invalid name is not
  106.      accepted; the commands to exit the minibuffer do not exit if the
  107.      current input is not valid.
  108.  
  109. Default
  110.      A default value of some sort is used if the user enters no text
  111.      in the minibuffer.  The default depends on the code character.
  112.  
  113. Prompt
  114.      A prompt immediately follows the code character.  The prompt
  115.      ends either with the end of the string or with a newline.
  116.  
  117. No I/O
  118.      This code letter computes an argument without reading any input.
  119.      Therefore, it does not use a prompt string, and any prompt
  120.      string you supply is ignored.
  121.  
  122.    Here are the code character descriptions for use with `interactive':
  123.  
  124. `a'
  125.      A function name (i.e., a symbol which is `fboundp').  Existing,
  126.      Completion, Prompt.
  127.  
  128. `b'
  129.      The name of an existing buffer.  By default, uses the name of
  130.      the current buffer (*note Buffers::.).  Existing, Completion,
  131.      Default, Prompt.
  132.  
  133. `B'
  134.      A buffer name.  The buffer need not exist.  By default, uses the
  135.      name of a recently used buffer other than the current buffer. 
  136.      Completion, Prompt.
  137.  
  138. `c'
  139.      A character.  The cursor does not move into the echo area. 
  140.      Prompt.
  141.  
  142. `C'
  143.      A command name (i.e., a symbol satisfying `commandp'). 
  144.      Existing, Completion, Prompt.
  145.  
  146. `d'
  147.      The position of point as a number (*note Point::.).  No I/O.
  148.  
  149. `D'
  150.      A directory name.  The default is the current default directory
  151.      of the current buffer, `default-directory' (*note System
  152.      Environment::.).  Existing, Completion, Default, Prompt.
  153.  
  154. `f'
  155.      A file name of an existing file (*note File Names::.).  The
  156.      default directory is `default-directory'.  Existing, Completion,
  157.      Default, Prompt.
  158.  
  159. `F'
  160.      A file name.  The file need not exist.  Completion, Default,
  161.      Prompt.
  162.  
  163. `k'
  164.      A key sequence (*note Keymap Terms::.).  This keeps reading
  165.      characters until a command (or undefined command) is found in
  166.      the current key maps.  The key sequence argument is represented
  167.      as a string.  The cursor does not move into the echo area. 
  168.      Prompt.
  169.  
  170.      This kind of input is used by commands such as `describe-key'
  171.      and `global-set-key'.
  172.  
  173. `m'
  174.      The position of the mark as a number.  No I/O.
  175.  
  176. `n'
  177.      A number read with the minibuffer.  If the input is not a
  178.      number, the user is asked to try again.  The prefix argument, if
  179.      any, is not used.  Prompt.
  180.  
  181. `N'
  182.      The raw prefix argument.  If the prefix argument is `nil', then
  183.      a number is read as with `n'.  Requires a number.  Prompt.
  184.  
  185. `p'
  186.      The numeric prefix argument.  (Note that this `p' is lower
  187.      case.) No I/O.
  188.  
  189. `P'
  190.      The raw prefix argument.  (Note that this `P' is upper case.)
  191.      *Note Prefix Command Arguments::.  No I/O.
  192.  
  193. `r'
  194.      Point and the mark, as two numeric arguments, smallest first. 
  195.      This is the only code letter that specifies two successive
  196.      arguments rather than one.  No I/O.
  197.  
  198. `s'
  199.      Arbitrary text, read in the minibuffer and returned as a string
  200.      (*note Text from Minibuffer::.).  Terminate the input with
  201.      either LFD or RET.  (`C-q' may be used to include either of
  202.      these characters in the input.)  Prompt.
  203.  
  204. `S'
  205.      An interned symbol whose name is read in the minibuffer.  Any
  206.      whitespace character terminates the input.  (Use `C-q' to
  207.      include whitespace in the string.)  Other characters that
  208.      normally terminate a symbol (e.g., parentheses and brackets) do
  209.      not do so here.  Prompt.
  210.  
  211. `v'
  212.      A variable declared to be a user option (i.e., satisfying
  213.      `user-variable-p').  *Note High-Level Completion::.  Existing,
  214.      Completion, Prompt.
  215.  
  216. `x'
  217.      A Lisp object specified in printed representation, terminated
  218.      with a LFD or RET.  The object is not evaluated.  *Note Object
  219.      from Minibuffer::.  Prompt.
  220.  
  221. `X'
  222.      A Lisp form is read as with `x', but then evaluated so that its
  223.      value becomes the argument for the command.  Prompt.
  224.  
  225.  
  226. 
  227. File: elisp,  Node: Interactive Examples,  Prev: Interactive Codes,  Up: Defining Commands
  228.  
  229. Examples of Using `interactive'
  230. -------------------------------
  231.  
  232.    Here are some examples of `interactive':
  233.  
  234.      (defun foo1 ()                ; `foo1' takes no arguments,
  235.          (interactive)             ; just moves forward two words.
  236.          (forward-word 2))
  237.           => foo1
  238.      
  239.      (defun foo2 (n)               ; `foo2' takes one argument,
  240.          (interactive "p")         ; which is the numeric prefix.
  241.          (forward-word (* 2 n)))
  242.           => foo2
  243.      
  244.      (defun foo3 (n)               ; `foo3' takes one argument,
  245.          (interactive "nCount:")   ; which is read with the Minibuffer.
  246.          (forward-word (* 2 n)))
  247.           => foo3
  248.      
  249.      (defun three-b (b1 b2 b3)
  250.        "Select three existing buffers (prompting for them in
  251.      the Minibuffer).  Put them into three windows, selecting the
  252.      last one."
  253.          (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
  254.          (delete-other-windows)
  255.          (split-window (selected-window) 8)
  256.          (switch-to-buffer b1)
  257.          (other-window 1)
  258.          (split-window (selected-window) 8)
  259.          (switch-to-buffer b2)
  260.          (other-window 1)
  261.          (switch-to-buffer b3))
  262.           => three-b
  263.      (three-b "*scratch*" "declarations.texi" "*mail*")
  264.           => nil
  265.  
  266.  
  267. 
  268. File: elisp,  Node: Interactive Call,  Next: Command Loop Info,  Prev: Defining Commands,  Up: Command Loop
  269.  
  270. Interactive Call
  271. ================
  272.  
  273.    After the command loop has translated a key sequence into a
  274. definition, it invokes that definition using the function
  275. `command-execute'.  If the definition is a function that is a
  276. command, `command-execute' calls `call-interactively', which reads
  277. the arguments and calls the command.  You can also call these
  278. functions yourself.
  279.  
  280.  * Function: commandp OBJECT
  281.      Returns `t' if OBJECT is suitable for calling interactively;
  282.      that is, if OBJECT is a command.  Otherwise, returns `nil'.
  283.  
  284.      The interactively callable objects include strings (treated as
  285.      keyboard macros), lambda expressions that contain a top-level
  286.      call to `interactive', autoload objects that are declared as
  287.      interactive (non-`nil' fourth argument to `autoload'), and some
  288.      of the primitive functions.
  289.  
  290.      A symbol is `commandp' if its function definition is `commandp'.
  291.  
  292.      Keys and keymaps are not commands.  Rather, they are used to
  293.      look up commands (*note Keymaps::.).
  294.  
  295.      See `documentation' in *Note Accessing Documentation::, for a
  296.      realistic example of using `commandp'.
  297.  
  298.  * Function: call-interactively COMMAND &optional RECORD-FLAG
  299.      This function calls the interactively callable function COMMAND,
  300.      reading arguments according to its interactive calling
  301.      specifications.  An error is signaled if COMMAND cannot be
  302.      called interactively (i.e., it is not a command).  Note that
  303.      strings are not accepted,  even though they are considered
  304.      commands.
  305.  
  306.      If RECORD-FLAG is non-`nil', then this command and its arguments
  307.      are unconditionally added to the list `command-history'. 
  308.      Otherwise, the command is added only if it uses the minibuffer
  309.      to read an argument.  *Note Command History::.
  310.  
  311.  * Function: command-execute COMMAND &optional RECORD-FLAG
  312.      This function executes COMMAND as an editing command.  The
  313.      argument COMMAND must satisfy the `commandp' predicate; i.e., it
  314.      must be an interactively callable function or a string.
  315.  
  316.      A string as COMMAND is executed with `execute-kbd-macro'.  A
  317.      function is passed to `call-interactively', along with the
  318.      optional RECORD-FLAG.
  319.  
  320.      A symbol is handled by using its function definition in its
  321.      place.  A symbol with an `autoload' definition counts as a
  322.      command if it was declared to stand for an interactively
  323.      callable function.  Such a definition is handled by loading the
  324.      specified library and then rechecking the definition of the
  325.      symbol.
  326.  
  327.  * Command: execute-extended-command PREFIX-ARGUMENT
  328.      This primitive function reads a command name from the minibuffer
  329.      using `completing-read' (*note Completion::.).  Then it uses
  330.      `command-execute' to call the specified command.  Whatever that
  331.      command returns becomes the value of `execute-extended-command'.
  332.  
  333.      If the command asks for a prefix argument, the value
  334.      PREFIX-ARGUMENT is supplied.  If `execute-extended-command' is
  335.      called interactively, the current raw prefix argument is used
  336.      for PREFIX-ARGUMENT, and thus passed on to whatever command is
  337.      run.
  338.  
  339.      `execute-extended-command' is the normal definition of `M-x', so
  340.      it uses the string `M-x ' as a prompt.  (It would be better to
  341.      take the prompt from the characters used to invoke
  342.      `execute-extended-command', but that is painful to implement.) 
  343.      A description of the value of the prefix argument, if any, also
  344.      becomes part of the prompt.
  345.  
  346.           (execute-extended-command 1)
  347.           ---------- Buffer: Minibuffer ----------
  348.           M-x forward-word RET
  349.           ---------- Buffer: Minibuffer ----------
  350.                => t
  351.  
  352.  * Function: interactive-p
  353.      This function returns `t' if the containing function (the one
  354.      that called `interactive-p') was called interactively, with
  355.      `call-interactively'.  (It makes no difference whether
  356.      `call-interactively' was called from Lisp or directly from the
  357.      editor command loop.)  Note that if the containing function was
  358.      called by Lisp evaluation (or with `apply' or `funcall'), then
  359.      it was not called interactively.
  360.  
  361.      The usual application of `interactive-p' is for deciding whether
  362.      to print an informative message.  As a special exception,
  363.      `interactive-p' returns `nil' whenever a keyboard macro is being
  364.      run.  This is to suppress the informative messages and speed
  365.      execution of the macro.
  366.  
  367.      For example:
  368.  
  369.           (defun foo ()
  370.             (interactive)
  371.             (and (interactive-p)
  372.                  (message "foo")))
  373.                => foo
  374.  
  375.              (defun bar ()
  376.             (interactive)
  377.             (setq foobar (list (foo) (interactive-p))))
  378.                => bar
  379.  
  380.  
  381.                     ;; Type `M-x foo'.
  382.                -| foo
  383.           
  384.           ;; Type `M-x bar'.
  385.           ;; This does not print anything.
  386.           
  387.           foobar
  388.                => (nil t)
  389.  
  390.  
  391. 
  392. File: elisp,  Node: Command Loop Info,  Next: Keyboard Input,  Prev: Interactive Call,  Up: Command Loop
  393.  
  394. Information from the Command Loop
  395. =================================
  396.  
  397.    The editor command loop sets several Lisp variables to keep status
  398. records for itself and for commands that are run.
  399.  
  400.  * Variable: last-command
  401.      This variable records the name of the previous command executed
  402.      by the command loop (the one before the current command). 
  403.      Normally the value is a symbol with a function definition, but
  404.      this is not guaranteed.
  405.  
  406.      The value is set by copying the value of `this-command' when a
  407.      command returns to the command loop, except when the command
  408.      specifies a prefix argument for the following command.
  409.  
  410.  * Variable: this-command
  411.      This variable records the name of the command now being executed
  412.      by editor command loop.  Like `last-command', it is normally a
  413.      symbol with a function definition.
  414.  
  415.      This variable is set by the command loop just before the command
  416.      is run, and its value is copied into `last-command' when the
  417.      command finishes (unless the command specifies a prefix argument
  418.      for the following command).
  419.  
  420.      Some commands change the value of this variable during their
  421.      execution, simply as a flag for whatever command runs next.  In
  422.      particular, the functions that kill text set `this-command' to
  423.      `kill-region' so that any kill commands immediately following
  424.      will know to append the killed text to the previous kill.
  425.  
  426.  * Function: this-command-keys
  427.      This function returns a string containing the key sequence that
  428.      invoked the present command, plus any previous commands that
  429.      generated the prefix argument for this command.
  430.  
  431.           (this-command-keys) ;; Now type `C-u C-x C-e'.
  432.                => "^U^X^E"
  433.  
  434.  * Variable: last-command-char
  435.      This variable is set to the last character that was typed on the
  436.      terminal and was part of a command.  The principal use of this
  437.      variable is in `self-insert-command', which uses it to decide
  438.      which character to insert.
  439.  
  440.           last-command-char ;; Now type `C-u C-x C-e'.
  441.                => 5
  442.  
  443.      The value is 5 because that is the ASCII code for `C-e'.
  444.  
  445.  * Variable: echo-keystrokes
  446.      This variable determines how much time should elapse before
  447.      command characters are echoed.  Its value must be an integer,
  448.      which specifies the number of seconds to wait before echoing. 
  449.      If the user types a prefix key (say `C-x') and then delays this
  450.      many seconds before continuing, the key `C-x' is echoed in the
  451.      echo area.  Any subsequent characters in the same command will
  452.      be echoed as well.
  453.  
  454.      If the value is zero, then command input is not echoed.
  455.  
  456.  
  457. 
  458. File: elisp,  Node: Keyboard Input,  Next: Quitting,  Prev: Command Loop Info,  Up: Command Loop
  459.  
  460. Keyboard Input
  461. ==============
  462.  
  463.    The editor command loop reads keyboard input using
  464. `read-key-sequence', which uses `read-char'.  These and other
  465. functions for keyboard input are also available for use in Lisp
  466. programs.  See also `momentary-string-display' in *Note Temporary
  467. Displays::, and `sit-for' in *Note Waiting::.  *Note Terminal
  468. Input::, for functions and variables for controlling terminal input
  469. modes and debugging terminal input.
  470.  
  471.  * Function: read-char
  472.      This function reads a character from the command input (either
  473.      from direct keyboard input or from an executing keyboard macro),
  474.      and returns it.
  475.  
  476.      No message is displayed to indicate that keyboard input is
  477.      expected.  If you want to display a message, call `message'
  478.      first.  If `cursor-in-echo-area' is non-`nil', then the cursor
  479.      moves to the echo area, to the end of any message displayed
  480.      there.  Otherwise the cursor does not move.  *Note The Echo
  481.      Area::.
  482.  
  483.      In the first example, the user types `1' (which is ASCII code
  484.      49).  The second example shows a keyboard macro definition that
  485.      calls `read-char' from the minibuffer.  `read-char' reads the
  486.      keyboard macro's very next character, which is `1'.  The value
  487.      of this function is displayed in the echo area by the command
  488.      `eval-expression'.
  489.  
  490.           (read-char)
  491.                => 49
  492.           
  493.           (symbol-function 'foo)
  494.                => "^[^[(read-char)^M1"
  495.           (execute-kbd-macro foo)
  496.                -| 49
  497.                => nil
  498.  
  499.  * Function: read-quoted-char &optional PROMPT
  500.      This function is like `read-char', except that if the first
  501.      character read is an octal digit (0-7), it reads up to two more
  502.      octal digits (but stopping if a non-octal digit is found) and
  503.      returns the character represented by those digits as an octal
  504.      number.
  505.  
  506.      Quitting is suppressed when the first character is read, so that
  507.      the user can enter a `C-g'.  *Note Quitting::.
  508.  
  509.      If PROMPT is supplied, it specifies a string for prompting the
  510.      user.  The prompt string is always printed in the echo area and
  511.      followed by a single `-'.
  512.  
  513.      In the following example, the user types in the octal number 177
  514.      (which is 127 in decimal).
  515.  
  516.           (read-quoted-char "What character")
  517.           
  518.           ---------- Echo Area ----------
  519.           What character-`177'
  520.           ---------- Echo Area ----------
  521.           
  522.                => 127
  523.  
  524.  * Function: read-key-sequence PROMPT
  525.      This function reads a key sequence and returns it as a string. 
  526.      It keeps reading characters until it has accumulated a full key
  527.      sequence; that is, enough characters to specify a non-prefix
  528.      command using the current local and global keymaps. 
  529.      `read-key-sequence' is used by the command loop to read command
  530.      input.
  531.  
  532.      If an input character is an upper case letter and has no
  533.      definition, but the lower case equivalent is defined, then the
  534.      character is converted to lower case.  Note that `lookup-key'
  535.      does not perform case conversion in this way.
  536.  
  537.      Quitting is suppressed inside `read-key-sequence'.  In other
  538.      words, a `C-g' typed while reading with this function is treated
  539.      like any other character, and `quit-flag' is not set.  *Note
  540.      Quitting::.
  541.  
  542.      The argument PROMPT is either a string to be displayed in the
  543.      echo area as a prompt, or `nil', meaning that no prompt is
  544.      displayed.
  545.  
  546.      In the example below, the prompt `?' is displayed in the echo
  547.      area, and the user types `C-x C-f'.
  548.  
  549.           (read-key-sequence "?")
  550.           
  551.           ---------- Echo Area ----------
  552.           ?`C-x C-f'
  553.           ---------- Echo Area ----------
  554.           
  555.                => "^X^F"
  556.  
  557.  * Variable: unread-command-char
  558.      This variable holds a character waiting to be read as the next
  559.      input from the command input stream, or to the integer -1 if no
  560.      character is waiting.  The variable is used because in some
  561.      cases an input function reads a character and then decides not
  562.      to use it.  Storing the character in this variable causes it to
  563.      be processed normally by the command loop or when `read-char' is
  564.      next called.
  565.  
  566.      For example, the function that governs prefix arguments reads
  567.      any number of digits.  When it finds a non-digit character, it
  568.      must unread the character so that it becomes input for the next
  569.      command.  Likewise, incremental search uses this feature to
  570.      unread a control character used to terminate the search.
  571.  
  572.  * Function: input-pending-p
  573.      This function determines whether command input is currently
  574.      available.  It returns immediately, with value `t' if there is
  575.      input, `nil' otherwise.  On rare occasions it may return `t'
  576.      when no input is available.
  577.  
  578.  * Variable: last-input-char
  579.      This variable records the last terminal input character read,
  580.      whether as part of a command or explicitly by a Lisp program.
  581.  
  582.      In the example below, a character is read (the character `1',
  583.      ASCII code 49).  It becomes the value of `last-input-char',
  584.      while `C-e' (from the `C-x C-e' command used to evaluate this
  585.      expression) remains the value of `last-command-char'.
  586.  
  587.           (progn (print (read-char))
  588.                  (print last-command-char)
  589.                  last-input-char)
  590.                -| 49
  591.                -| 5
  592.                => 49
  593.  
  594.  * Function: discard-input
  595.      This function discards the contents of the terminal input buffer
  596.      and cancels any keyboard macro that might be in the process of
  597.      definition.  It returns `nil'.
  598.  
  599.      In the following example, the user may type a number of
  600.      characters right after starting the evaluation of the form. 
  601.      After the `sleep-for' finishes sleeping, any characters that
  602.      have been typed are discarded.
  603.  
  604.           (progn (sleep-for 2)
  605.             (discard-input))
  606.                => nil
  607.  
  608.  
  609. 
  610. File: elisp,  Node: Quitting,  Next: Prefix Command Arguments,  Prev: Keyboard Input,  Up: Command Loop
  611.  
  612. Quitting
  613. ========
  614.  
  615.    Typing `C-g' while the command loop has run a Lisp function causes
  616. Emacs to "quit" whatever it is doing.  This means that control
  617. returns to the innermost active command loop.
  618.  
  619.    Typing `C-g' while the command loop is waiting for keyboard input
  620. does not cause a quit; it acts as an ordinary input character.  In
  621. the simplest case, you cannot tell the difference, because `C-g'
  622. normally runs the command `keyboard-quit', whose effect is to quit. 
  623. However, when `C-g' follows a prefix key, the result is an undefined
  624. key.  The effect is to cancel the prefix key as well as any prefix
  625. argument.
  626.  
  627.    In the minibuffer, `C-g' has a different definition: it aborts out
  628. of the minibuffer.  This means, in effect, that it exits the
  629. minibuffer and then quits.  (Simply quitting would return to the
  630. command loop *within* the minibuffer.)  The reason why `C-g' does not
  631. quit directly when the command reader is reading input is so that its
  632. meaning can be redefined in the minibuffer in this way.  `C-g'
  633. following a prefix key is not redefined in the minibuffer, and it has
  634. its normal effect of canceling the prefix key and prefix argument. 
  635. This too would not be possible if `C-g' quit directly.
  636.  
  637.    `C-g' causes a quit by setting the variable `quit-flag' to a
  638. non-`nil' value.  Emacs checks this variable at appropriate times and
  639. quits if it is not `nil'.  Setting `quit-flag' non-`nil' in any way
  640. thus causes a quit.
  641.  
  642.    At the level of C code, quits cannot happen just anywhere; only at
  643. the special places which check `quit-flag'.  The reason for this is
  644. that quitting at other places might leave an inconsistency in Emacs's
  645. internal state.  Because quitting is delayed until a safe place,
  646. quitting  cannot make Emacs crash.
  647.  
  648.    Certain functions such as `read-key-sequence' or
  649. `read-quoted-char' prevent quitting entirely even though they wait
  650. for input.  Instead of quitting, `C-g' serves as the requested input.
  651. In the case of `read-key-sequence', this serves to bring about the
  652. special behavior of `C-g' in the command loop.  In the case of
  653. `read-quoted-char', this is so that `C-q' can be used to quote a
  654. `C-g'.
  655.  
  656.    You can prevent quitting for a portion of a Lisp function by
  657. binding the variable `inhibit-quit' to a non-`nil' value.  Then,
  658. although `C-g' still sets `quit-flag' to `t' as usual, the usual
  659. result of this--a quit--is prevented.  Eventually, `inhibit-quit'
  660. will become `nil' again, such as when its binding is unwound at the
  661. end of a `let' form.  At that time, if `quit-flag' is still
  662. non-`nil', the requested quit happens immediately.  This behavior is
  663. ideal for a "critical section", where you wish to make sure that
  664. quitting does not happen within that part of the program.
  665.  
  666.    In some functions (such as `read-quoted-char'), `C-g' is handled
  667. in a special way which does not involve quitting.  This is done by
  668. reading the input with `inhibit-quit' bound to `t' and setting
  669. `quit-flag' to `nil' before `inhibit-quit' becomes `nil' again.  This
  670. excerpt from the definition of `read-quoted-char' shows how this is
  671. done; it also shows that normal quitting is permitted after the first
  672. character of input.
  673.  
  674.      (defun read-quoted-char (&optional prompt)
  675.        "...DOCUMENTATION..."
  676.        (let ((count 0) (code 0) char)
  677.          (while (< count 3)
  678.            (let ((inhibit-quit (zerop count))
  679.                  (help-form nil))
  680.              (and prompt (message "%s-" prompt))
  681.              (setq char (read-char))
  682.              (if inhibit-quit (setq quit-flag nil)))
  683.            ...)
  684.          (logand 255 code)))
  685.  
  686.  * Variable: quit-flag
  687.      If this variable is non-`nil', then Emacs quits immediately,
  688.      unless `inhibit-quit' is non-`nil'.  Typing `C-g' sets
  689.      `quit-flag' non-`nil', regardless of `inhibit-quit'.
  690.  
  691.  * Variable: inhibit-quit
  692.      This variable determines whether Emacs should quit when
  693.      `quit-flag' is set to a value other than `nil'.  If
  694.      `inhibit-quit' is non-`nil', then `quit-flag' has no special
  695.      effect.
  696.  
  697.  * Command: keyboard-quit
  698.      This function signals the `quit' condition with `(signal 'quit
  699.      nil)'.  This is the same thing that quitting does.  (See
  700.      `signal' in *Note Errors::.)
  701.  
  702.    You can specify a character other than `C-g' to use for quitting. 
  703. See the function `set-input-mode' in *Note Terminal Input::.
  704.  
  705.  
  706. 
  707. File: elisp,  Node: Prefix Command Arguments,  Next: Recursive Editing,  Prev: Quitting,  Up: Command Loop
  708.  
  709. Prefix Command Arguments
  710. ========================
  711.  
  712.    Most Emacs commands can use a "prefix argument", a number
  713. specified before the command itself.  (Don't confuse prefix arguments
  714. with prefix keys.)  The prefix argument is represented by a value
  715. that is always available (though it may be `nil', meaning there is no
  716. prefix argument).  Each command may use the prefix argument or ignore
  717. it.
  718.  
  719.    There are two representations of the prefix argument: "raw" and
  720. "numeric".  The editor command loop uses the raw representation
  721. internally, and so do the Lisp variables that store the information,
  722. but commands can request either representation.
  723.  
  724.    Here are the possible values of a raw prefix argument:
  725.  
  726.    * `nil', meaning there is no prefix argument.  Its numeric value
  727.      is 1, but numerous commands make a distinction between `nil' and
  728.      the integer 1.
  729.  
  730.    * An integer, which stands for itself.
  731.  
  732.    * A list of one element, which is an integer.  This form of prefix
  733.      argument results from one or a succession of `C-u''s with no
  734.      digits.  The numeric value is the integer in the list, but some
  735.      commands make a distinction between such a list and an integer
  736.      alone.
  737.  
  738.    * The symbol `-'.  This indicates that `M--' or `C-u -' was typed,
  739.      without following digits.  The equivalent numeric value is -1,
  740.      but some commands make a distinction between the integer -1 and
  741.      the symbol `-'.
  742.  
  743.    The various possibilities may be illustrated by calling the
  744. following function with various prefixes:
  745.  
  746.      (defun print-prefix (arg)
  747.        "Print the value of the raw prefix arg at point."
  748.        (interactive "P")
  749.        (message "%s" arg))
  750.  
  751. Here are the results of calling `print-prefix' with various raw
  752. prefix arguments:
  753.  
  754.              M-x print-prefix  -| nil
  755.      
  756.      C-u     M-x print-prefix  -| (4)
  757.      
  758.      C-u C-u M-x print-prefix  -| (16)
  759.      
  760.      C-u 3   M-x print-prefix  -| 3
  761.      
  762.      M-3     M-x print-prefix  -| 3      ; (Same as `C-u 3'.)
  763.      
  764.      C-u -   M-x print-prefix  -| -      
  765.      
  766.      M- -    M-x print-prefix  -| -      ; (Same as `C-u -'.)
  767.      
  768.      C-u -7  M-x print-prefix  -| -7     
  769.      
  770.      M- -7   M-x print-prefix  -| -7     ; (Same as `C-u -7'.)
  771.  
  772.    There are two variables used to store the prefix argument:
  773. `prefix-arg' and `current-prefix-arg'.  Commands such as
  774. `universal-argument' that set up prefix arguments for other commands
  775. store them in `prefix-arg'.  In contrast, `current-prefix-arg'
  776. conveys the prefix argument to the current command, so setting it has
  777. no effect on the prefix arguments for future commands.
  778.  
  779.    Normally, commands specify which representation to use for the
  780. prefix argument, either numeric or raw, in the `interactive'
  781. declaration.  (*Note Interactive Call::.)  Alternatively, functions
  782. may look at the value of the prefix argument directly in the variable
  783. `current-prefix-arg', but this is less clean.
  784.  
  785.    Don't call `universal-argument', `digit-argument', or
  786. `negative-argument' unless you intend to let the user enter the
  787. prefix argument for the *next* command.
  788.  
  789.  * Command: universal-argument
  790.      This command reads input and specifies a prefix argument for the
  791.      following command.  Don't call this command yourself unless you
  792.      know what you are doing.
  793.  
  794.  * Command: digit-argument ARG
  795.      This command adds to the prefix argument for the following
  796.      command.  The argument ARG is the raw prefix argument as it was
  797.      before this command; it is used to compute the updated prefix
  798.      argument.  Don't call this command yourself unless you know what
  799.      you are doing.
  800.  
  801.  * Command: negative-argument ARG
  802.      This command adds to the numeric argument for the next command. 
  803.      The argument ARG is the raw prefix argument as it was before
  804.      this command; its value is negated to form the new prefix
  805.      argument.  Don't call this command yourself unless you know what
  806.      you are doing.
  807.  
  808.  * Function: prefix-numeric-value ARG
  809.      This function returns the numeric meaning of a valid raw prefix
  810.      argument value, ARG.  The argument may be a symbol, a number, or
  811.      a list.  If it is `nil', the value 1 is returned; if it is any
  812.      other symbol, the value -1 is returned.  If it is a number, that
  813.      number is returned; if it is a list, the CAR of that list (which
  814.      should be a number) is returned.
  815.  
  816.  * Variable: current-prefix-arg
  817.      This variable is the value of the raw prefix argument for the
  818.      *current* command.  Commands may examine it directly, but the
  819.      usual way to access it is with `(interactive "P")'.
  820.  
  821.  * Variable: prefix-arg
  822.      The value of this variable is the raw prefix argument for the
  823.      *next* editing command.  Commands that specify prefix arguments
  824.      for the following command work by setting this variable.
  825.  
  826.  
  827. 
  828. File: elisp,  Node: Recursive Editing,  Next: Disabling Commands,  Prev: Prefix Command Arguments,  Up: Command Loop
  829.  
  830. Recursive Editing
  831. =================
  832.  
  833.    The Emacs command loop is entered automatically when Emacs starts
  834. up.  This top-level invocation of the command loop is never exited
  835. until the Emacs is killed.  Lisp programs can also invoke the command
  836. loop.  Since this makes more than one activation of the command loop,
  837. we call it "recursive editing".  A recursive editing level has the
  838. effect of suspending whatever command invoked it and permitting the
  839. user to do arbitrary editing before resuming that command.
  840.  
  841.    The commands available during recursive editing are the same ones
  842. available in the top-level editing loop and defined in the keymaps. 
  843. Only a few special commands exit the recursive editing level; the
  844. others return to the recursive editing level when finished.  (The
  845. special commands for exiting are always available, but do nothing
  846. when recursive editing is not in progress.)
  847.  
  848.    All command loops, including recursive ones, set up all-purpose
  849. error handlers so that an error in a command run from the command
  850. loop will not exit the loop.
  851.  
  852.    Minibuffer input is a special kind of recursive editing.  It has a
  853. few special wrinkles, such as enabling display of the minibuffer and
  854. the minibuffer window, but fewer than you might suppose.  Certain
  855. keys behave differently in the minibuffer, but that is only because
  856. of the minibuffer's local map; if you switch windows, you get the
  857. usual Emacs commands.
  858.  
  859.    To invoke a recursive editing level, call the function
  860. `recursive-edit'.  This function contains the command loop; it also
  861. contains a call to `catch' with tag `exit', which makes it possible
  862. to exit the recursive editing level by throwing to `exit' (*note
  863. Catch and Throw::.).  If you throw a value other than `t', then
  864. `recursive-edit' returns normally to the function that called it. 
  865. The command `C-M-c' (`exit-recursive-edit') does this.  Throwing a
  866. `t' value causes `recursive-edit' to quit, so that control returns to
  867. the command loop one level up.  This is called "aborting", and is
  868. done by `C-]' (`abort-recursive-edit').
  869.  
  870.    Most applications should not use recursive editing, except as part
  871. of using the minibuffer.  Usually it is more convenient for the user
  872. if you change the major mode of the current buffer temporarily to a
  873. special major mode, which has a command to go back to the previous
  874. mode.  (This technique is used by the `w' command in Rmail.)  Or, if
  875. you wish to give the user different text to edit "recursively",
  876. create and select a new buffer in a special mode.  In this mode,
  877. define a command to complete the processing and go back to the
  878. previous buffer.  (The `m' command in Rmail does this.)
  879.  
  880.    Recursive edits are useful in debugging.  You can insert a call to
  881. `debug' into a function definition as a sort of breakpoint, so that
  882. you can look around when the function gets there.  `debug' invokes a
  883. recursive edit but also provides the other features of the debugger.
  884.  
  885.    Recursive editing levels are also used when you type `C-r' in
  886. `query-replace' or use `C-x q' (`kbd-macro-query').
  887.  
  888.  * Function: recursive-edit
  889.      This function invokes the editor command loop.  It is called
  890.      automatically by the initialization of Emacs, to let the user
  891.      begin editing.  When called from a Lisp program, it enters a
  892.      recursive editing level.
  893.  
  894.      In the following example, the function `simple-rec' first
  895.      advances point one word, then enters a recursive edit, printing
  896.      out a message in the echo area.  The user can then do any
  897.      editing desired, and then type `C-M-c' to exit and continue
  898.      executing `simple-rec'.
  899.  
  900.           (defun simple-rec ()
  901.             (forward-word 1)
  902.             (message "Recursive edit in progress.")
  903.             (recursive-edit)
  904.             (forward-word 1))
  905.                => simple-rec
  906.           (simple-rec)
  907.                => nil
  908.  
  909.  * Command: exit-recursive-edit
  910.      This function exits from the innermost recursive edit (including
  911.      minibuffer input).  Its definition is effectively `(throw 'exit
  912.      nil)'.
  913.  
  914.  * Command: abort-recursive-edit
  915.      This function aborts the command that requested the innermost
  916.      recursive edit (including minibuffer input), by signaling `quit'
  917.      after exiting the recursive edit.  Its definition is effectively
  918.      `(throw 'exit t)'.  *Note Quitting::.
  919.  
  920.  * Command: top-level
  921.      This function exits all recursive editing levels; it does not
  922.      return a value, as it jumps completely out of any computation
  923.      directly back to the main command loop.
  924.  
  925.  * Function: recursion-depth
  926.      This function returns the current depth of recursive edits. 
  927.      When no recursive edit is active, it returns 0.
  928.  
  929.  
  930. 
  931. File: elisp,  Node: Disabling Commands,  Next: Command History,  Prev: Recursive Editing,  Up: Command Loop
  932.  
  933. Disabling Commands
  934. ==================
  935.  
  936.    "Disabling a command" marks the command as requiring user
  937. confirmation before it can be executed.  Disabling is used for
  938. commands which might be confusing to beginning users, to prevent them
  939. from using the commands by accident.
  940.  
  941.    The low-level mechanism for disabling a command is to put a
  942. non-`nil' `disabled' property on the Lisp symbol for the command. 
  943. These properties are normally set up by the user's `.emacs' file with
  944. Lisp expressions such as this:
  945.  
  946.      (put 'upcase-region 'disabled t)
  947.  
  948. For a few commands, these properties are present by default and may
  949. be removed by the `.emacs' file.
  950.  
  951.    If the value of the `disabled' property is a string, that string
  952. is included in the message printed when the command is used:
  953.  
  954.      (put 'delete-region 'disabled
  955.           "Text deleted this way cannot be yanked back!\n")
  956.  
  957.    *Note : (emacs)Disabling, for the details on what happens when a
  958. disabled command is invoked interactively.  Disabling a command has
  959. no effect on calling it as a function from Lisp programs.
  960.  
  961.  * Command: enable-command COMMAND
  962.      Allow COMMAND to be executed without special confirmation from
  963.      now on.  The user's `.emacs' file is optionally altered so that
  964.      this will apply to future sessions.
  965.  
  966.  * Command: disable-command COMMAND
  967.      Require special confirmation to execute COMMAND from now on. 
  968.      The user's `.emacs' file is optionally altered so that this will
  969.      apply to future sessions.
  970.  
  971.  * Variable: disabled-command-hook
  972.      The value of this variable is a function to be called instead of
  973.      any command that is disabled (i.e., that has a non-`nil'
  974.      disabled property).  By default, the value of
  975.      `disabled-command-hook' is a function defined to ask the user
  976.      whether to proceed.
  977.  
  978.  
  979. 
  980. File: elisp,  Node: Command History,  Next: Keyboard Macros,  Prev: Disabling Commands,  Up: Command Loop
  981.  
  982. Command History
  983. ===============
  984.  
  985.    The command loop keeps a history of the complex commands that have
  986. been executed, to make it convenient to repeat these commands.  A
  987. "complex command" is one for which the interactive argument reading
  988. uses the minibuffer.  This includes any `M-x' command, any `M-ESC'
  989. command, and any command whose `interactive' specification reads an
  990. argument from the minibuffer.  Explicit use of the minibuffer during
  991. the execution of the command itself does not cause the command to be
  992. considered complex.
  993.  
  994.  * Variable: command-history
  995.      This variable's value is a list of recent complex commands, each
  996.      represented as a form to evaluate.  It continues to accumulate
  997.      all complex commands for the duration of the editing session,
  998.      but all but the first (most recent) thirty elements are deleted
  999.      when a garbage collection takes place (*note Garbage
  1000.      Collection::.).
  1001.  
  1002.           command-history
  1003.           => ((switch-to-buffer "chistory.texi")
  1004.               (describe-key "^X^[")
  1005.               (visit-tags-table "~/emacs/src/")
  1006.               (find-tag "repeat-complex-command"))
  1007.  
  1008.    There are a number of commands and even two entire modes devoted
  1009. to facilitating the editing and recall of previous commands.  The
  1010. commands `repeat-complex-command', and `list-command-history' are
  1011. described in the user manual (*note : (emacs)Repetition.).
  1012.  
  1013.  * Variable: repeat-complex-command-map
  1014.      The value of this variable is a sparse keymap used by the
  1015.      minibuffer inside of `read-complex-command'.
  1016.  
  1017.  
  1018. 
  1019. File: elisp,  Node: Keyboard Macros,  Prev: Command History,  Up: Command Loop
  1020.  
  1021. Keyboard Macros
  1022. ===============
  1023.  
  1024.    A "keyboard macro" is a canned sequence of keystrokes that can be
  1025. considered a command and made the definition of a key.  Don't confuse
  1026. keyboard macros with Lisp macros (*note Macros::.).
  1027.  
  1028.  * Function: execute-kbd-macro MACRO &optional COUNT
  1029.      This function executes MACRO as a string of editor commands.  If
  1030.      MACRO is a string, then the characters in that string are
  1031.      executed exactly as if they had been typed as command input.
  1032.  
  1033.      If MACRO is a symbol, then its function definition is used in
  1034.      place of MACRO.  If that is another symbol, this process repeats.
  1035.      Eventually the result should be a string.  If the result is
  1036.      neither a symbol nor a string, an error is signaled.
  1037.  
  1038.      The argument COUNT is a repeat count; MACRO is executed that
  1039.      many times.  If COUNT is omitted or `nil', MACRO is executed
  1040.      once.  If it is 0, MACRO is executed over and over until it
  1041.      encounters an error or a failing search.
  1042.  
  1043.  * Variable: last-kbd-macro
  1044.      This variable is the definition of the most recently defined
  1045.      keyboard macro.  Its value is a string or `nil'.
  1046.  
  1047.  * Variable: executing-macro
  1048.      This variable contains the string that defines the keyboard
  1049.      macro that is currently executing.  It is `nil' if no macro is
  1050.      currently executing.
  1051.  
  1052.  * Variable: defining-kbd-macro
  1053.      This variable indicates whether a keyboard macro is being
  1054.      defined.  It is set to `t' by `start-kbd-macro', and `nil' by
  1055.      `end-kbd-macro'.  It is not hard to use this variable to make a
  1056.      command behave differently when run from a keyboard macro
  1057.      (perhaps indirectly by calling `interactive-p').  However, do
  1058.      not set this variable yourself.
  1059.  
  1060.    The user-level commands for defining, running and editing keyboard
  1061. macros include `call-last-kbd-macro', `insert-kbd-macro',
  1062. `start-kbd-macro', `end-kbd-macro', `kbd-macro-query', and
  1063. `name-last-kbd-macro'.  They are described in the user's manual
  1064. (*note : (emacs)Keyboard Macros.).
  1065.  
  1066.  
  1067. 
  1068. File: elisp,  Node: Keymaps,  Next: Modes,  Prev: Command Loop,  Up: Top
  1069.  
  1070. Keymaps
  1071. *******
  1072.  
  1073.    The bindings between keyboard input and commands are recorded in
  1074. data structures called "keymaps".  Each binding in a keymap
  1075. associates (or "binds") an individual character either with another
  1076. keymap or with a command.  When a character is bound to a keymap,
  1077. that keymap is used to look up the next character typed; this
  1078. continues until a command is found.  This process is called "key
  1079. lookup".
  1080.  
  1081. * Menu:
  1082.  
  1083. * Keymap Terms::        Definitions of terms pertaining to keymaps.
  1084. * Creating Keymaps::    Functions to create and copy keymaps.
  1085. * Key Lookup::                  How extracting elements from keymaps works.
  1086. * Functions for Key Lookup::    How to request key lookup.
  1087. * Prefix Keys::                 Defining a key with a keymap as its definition.
  1088. * Global and Local Keymaps::    Each buffer has a local keymap
  1089.                                    to override the standard (global) bindings.
  1090. * Changing Key Bindings::       Redefining a key in a keymap.
  1091. * Key Binding Commands::        Interactive interfaces for redefining keys.
  1092. * Scanning Keymaps::            Looking through all keymaps, for printing help.
  1093.  
  1094.  
  1095. 
  1096. File: elisp,  Node: Keymap Terms,  Next: Creating Keymaps,  Prev: Keymaps,  Up: Keymaps
  1097.  
  1098. Keymaps: Terminology
  1099. ====================
  1100.  
  1101.    A "keymap" is a table mapping characters to definitions (which can
  1102. be any Lisp objects, though only certain types are meaningful for
  1103. execution by the command loop).  Given a character and a keymap,
  1104. Emacs can get the character's definition.
  1105.  
  1106.    A sequence of keyboard input characters that form a unit is called
  1107. a "key sequence", or "key" for short.  A sequence of one character is
  1108. always a key sequence, and so are some multicharacter sequences.
  1109.  
  1110.    A keymap determines a binding or definition for any key sequence. 
  1111. If the key sequence is a single character, its binding is the
  1112. definition of the character in the keymap.  The binding of a
  1113. multicharacter key sequence is found by an iterative process: the
  1114. binding of the first character is found, and must be a keymap; then
  1115. the second character's binding is found in that keymap, and so on
  1116. until all the characters in the key sequence are used up.
  1117.  
  1118.    If the binding of a key sequence is a keymap, we call the key
  1119. sequence a "prefix key".  Otherwise, we call it a "complete key"
  1120. (because no more characters can be added to it).  If the binding is
  1121. `nil', we call the key "undefined".  Examples of prefix keys are
  1122. `C-c', `C-x', and `C-x 4'.  Examples of defined complete keys are
  1123. `X', RET, and `C-x 4 C-f'.  Examples of undefined complete keys are
  1124. `C-x C-g', and `C-c 3'.  *Note Prefix Keys::, for more details.
  1125.  
  1126.    The rule for finding the binding of a key sequence assumes that
  1127. the intermediate bindings (found for the characters before the last)
  1128. are all keymaps; if this is not so, the sequence of characters does
  1129. not form a unit--it is not really a key sequence.  In other words,
  1130. removing one or more characters from the end of any key must always
  1131. yield a prefix key.  For example, `C-f C-f' is not a key; `C-f' is
  1132. not a prefix key, so a longer sequence starting with `C-f' cannot be
  1133. a key.  Note that the set of possible multicharacter key sequences
  1134. depends on the bindings for prefix keys; therefore, it can be
  1135. different for different keymaps, and can change when bindings are
  1136. changed.  However, a one-character sequence is always a key sequence,
  1137. because it does not depend on any prefix keys for its validity.
  1138.  
  1139.    At any time, two primary keymaps are in use for finding key
  1140. bindings: the "global map", which is shared by all buffers, and the
  1141. "local keymap", which is usually associated with a specific major
  1142. mode.  The local keymap bindings shadow (i.e., take precedence over)
  1143. the corresponding global bindings.  *Note Global and Local Keymaps::,
  1144. for details.
  1145.  
  1146.  
  1147. 
  1148. File: elisp,  Node: Creating Keymaps,  Next: Key Lookup,  Prev: Keymap Terms,  Up: Keymaps
  1149.  
  1150. Creating Keymaps
  1151. ================
  1152.  
  1153.    A keymap can be represented as one of two kinds of Lisp object: a
  1154. vector or a list.  A "full keymap" is a vector of length 128.  The
  1155. binding for a character in such a keymap is found by indexing into
  1156. the vector with the character as the index.
  1157.  
  1158.    A "sparse keymap" is a list whose CAR is the symbol `keymap', and
  1159. whose remaining elements are cons cells of the form `(CHAR .
  1160. BINDING)'.  It is called a sparse keymap because it stores only the
  1161. entries which are significant.  Use a sparse keymap when you expect
  1162. only a few entries.  (`define-key' automatically creates sparse
  1163. keymaps for intermediate keymaps.)
  1164.  
  1165.    Keymaps record directly only character codes less than 128; they
  1166. are unable to handle directly the META characters, whose codes are
  1167. from 128 to 255.  Instead, META characters are regarded for purposes
  1168. of key lookup as sequences of two characters, the first of which is
  1169. ESC (the usual value of `meta-prefix-char').  Thus, the key `M-a' is
  1170. really represented as `ESC a', and its global binding is found at the
  1171. slot for `a' in `esc-map'.
  1172.  
  1173.    Here as an example is the local keymap for Lisp mode, a sparse
  1174. keymap.  It defines `C-c C-l' as the `run-lisp' command, `M-C-q' as
  1175. `indent-sexp', and `M-C-x' as `lisp-send-defun'.
  1176.  
  1177.      lisp-mode-map
  1178.      => 
  1179.      (keymap 
  1180.       (9 . lisp-indent-line)                 ; TAB
  1181.       (127 . backward-delete-char-untabify)  ; DEL
  1182.       (3 keymap 
  1183.          (12 . run-lisp))                    ; `C-c C-l'
  1184.       (27 keymap 
  1185.           (17 . indent-sexp)                 ; `M-C-q', treated as `ESC C-q'
  1186.           (24 . lisp-send-defun)))           ; `M-C-x', treated as `ESC C-x'
  1187.  
  1188.  * Function: keymapp OBJECT
  1189.      This function returns `t' if OBJECT is a keymap, `nil'
  1190.      otherwise.  A keymap is either a vector of length 128, or a list
  1191.      with the form `(keymap PAIRS...)', where PAIRS stands for a
  1192.      series of associations, cons cells of the form `(CHAR . BINDING)'.
  1193.  
  1194.           (keymapp '(keymap))
  1195.               => t
  1196.           (keymapp (current-global-map))
  1197.               => t
  1198.  
  1199.  * Function: make-keymap
  1200.      This function creates and returns a new full keymap (i.e., a
  1201.      vector of length 128).  All entries in the keymap are `nil',
  1202.      which means that no characters are defined.
  1203.  
  1204.           (make-keymap)
  1205.               => [nil nil nil ... nil nil]
  1206.  
  1207.  * Function: make-sparse-keymap
  1208.      This function creates and returns a new sparse keymap with no
  1209.      entries.  In this keymap, no characters are defined.
  1210.  
  1211.           (make-sparse-keymap)
  1212.               => (keymap)
  1213.  
  1214.  * Function: copy-keymap KEYMAP
  1215.      This function returns a copy of KEYMAP.  Any keymaps which
  1216.      appear directly as bindings in KEYMAP are also copied
  1217.      recursively, and so on to any number of levels.  However,
  1218.      recursive copying does not take place when the definition of a
  1219.      character is a symbol whose function definition is a keymap; the
  1220.      same symbol appears in the new copy.
  1221.  
  1222.           (setq map (copy-keymap (current-local-map)))
  1223.           => (keymap
  1224.                (27 keymap         ; (This implements META characters.)
  1225.                  (83 . center-paragraph)
  1226.                  (115 . center-line))
  1227.                (9 . tab-to-tab-stop))
  1228.           
  1229.           (eq map (current-local-map))
  1230.               => nil
  1231.           (equal map (current-local-map))
  1232.               => t
  1233.  
  1234.  
  1235.